Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:PageLayout;,PageLayout

Inherits From:	Panel : Window : Responder : Object

Declared In:	appkit/PageLayout.h

Class Description

PageLayout is a type of Panel that queries the user for information such as paper type and orientation.  This information is passed to the Application object's PrintInfo object, and is later used when printing.  The PageLayout panel is created, displayed, and run (in a modal loop) when a runPageLayout: message is sent to the Application object.   By default, this message is sent up the responder chain when the user clicks the Page Layout menu item. 

Each application can have but one PageLayout object.  If you're creating a subclass of PrintPanel, you should send your subclass' class object a new message (without invoking alloc or allocFromZone:) before any runPageLayout: messages are sent to ensure that an instance of your subclass is the unique PrintPanel object for your application.  

You can add your own controls to the Page Layout panel through the setAccessoryView: method.  The panel is automatically resized to accommodate the View that you've added.  Note that you can't retrieve the PageLayout's settings through messages to the object.  If the controls that you add depend on the values of the existing controls (or vice versa), you must subclass PageLayout and query or set these controls by sending messages to the instance variables that represent them.   

Instance Variables

id appIcon;

id height;

id width;

id ok;

id cancel;

id orientation;

id scale;

id paperSizeList;

id layoutList;

id unitsList;

int exitTag;

id paperView;

id accessoryView;

appIcon 	The Button object with the Application's icon.

height 	The Form object for paper height.

width 	The Form object for paper width.

ok 	The OK Button object.

cancel 	The Cancel Button object.

orientation 	The portrait/landscape Matrix object.

scale 	The TextField for the scaling factor.

paperSizeList 	The Button object for the PopUpList of paper choices.

layoutList 	The Button object for the PopUpList of layout choices.

unitsList 	The Button object for the PopUpList of unit choices.

exitTag 	The tag of the Button object the user clicked to exit the Panel.

paperView 	The View used to display the size and orientation of the selected paper type. 

accessoryView 	The optional View added by the application.

Method Types

Creating and freeing a PageLayout instance	
+ new
+ newContent:style:backing:buttonMask:defer:
- free

Running the PageLayout panel	- runModal

Customizing the panel	- setAccessoryView:
- accessoryView

Updating the panel's display	- pickedLayout: 
- pickedOrientation: 
- pickedPaperSize: 
- pickedUnits: 
- textDidEnd:endChar: 
- textWillChange:
- convertOldFactor:newFactor: 
- pickedButton: 

Communicating with the PrintInfo object
- readPrintInfo 
- writePrintInfo

Class Methods

NS_DEV_DOCFOR:objc_method:[PageLayout-alloc];,alloc

Generates an error message.  This method cannot be used to create PageLayout instances; use new instead.

NS_DEV_DOCFOR:objc_method:[PageLayout-allocFromZone:];,allocFromZone:

Generates an error message.  This method cannot be used to create PageLayout instances; use new instead.

NS_DEV_DOCFOR:objc_method:[PageLayout-new];,new

+ new

Returns the application's sole PageLayout object, creating it if necessary.  This method is invoked by Application's runPageLayout: method; by extension, it's invoked when the user clicks the Page Layout menu item. 

NS_DEV_DOCFOR:objc_method:[PageLayout-newContent:style:backing:buttonMask:defer:];,newContent:style:backing:buttonMask:defer:

+ newContent:(const NXRect *)contentRect
style:(int)aStyle
backing:(int)bufferingType
buttonMask:(int)mask
defer:(BOOL)flag

Initializes the PageLayout object.  You never invoke this method directly; use new instead.

Instance Methods

NS_DEV_DOCFOR:objc_method:[PageLayout-accessoryView];,accessoryView

- accessoryView

Returns the custom accessory View set by setAccessoryView:.

See also:  - setAccessoryView:

NS_DEV_DOCFOR:objc_method:[PageLayout-convertOldFactor:newFactor:];,convertOldFactor:newFactor:

- convertOldFactor:(float *)old newFactor:(float *)new

The standard unit used to measure a paper's dimensions is a point (for example, the PrintInfo object defines a paper's size in units of points).  This method returns, by reference, a value that expresses the ratio between a point and the currently chosen unit of measurement.  In general, both old and new are set to this value.  The only time the values returned in the arguments differ is when the unit of measurement is being changed.  Specifically, if you invoke this method from within pickedUnits:, old gives the old ratio and new gives the new one.  Returns self.

See also:  - pickedUnits:

NS_DEV_DOCFOR:objc_method:[PageLayout-free];,free

- free

Frees the PageLayout object and its contents, including the accessory View.

NS_DEV_DOCFOR:objc_method:[PageLayout-pickedButton:];,pickedButton:

- pickedButton:sender

The action of the OK and Cancel buttons, this method ends the Page Layout panel's modal run.  If the OK button inspired this method, the height, width, and scale entries must be acceptable (they must hold positive numbers), otherwise the unacceptable entry is selected and the panel isn't stopped.   If the panel is being cancelled, then it's stopped regardless of the entries' acceptability.  If the panel is successfully stopped, the exitTag instance variable is set to the sender's tag (NX_OKTAG or NX_CANCELTAG).  Returns self.

NS_DEV_DOCFOR:objc_method:[PageLayout-pickedLayout:];,pickedLayout:

- pickedLayout:sender

Performed when the user selects an item from the Layout list.  You can get the new layout with the message 

[[sender selectedCell] title]

Returns self.

NS_DEV_DOCFOR:objc_method:[PageLayout-pickedOrientation:];,pickedOrientation:

- pickedOrientation:sender

Performed when the user selects a page orientation from the Portrait/Landscape matrix.  This method updates the Width and Height fields, and redraws the paper view.  You can get the new orientation by sending the message 

int orientation = [sender selectedCol]

and comparing the returned value to NX_LANDSCAPE and NX_PORTRAIT.  Returns self.

NS_DEV_DOCFOR:objc_method:[PageLayout-pickedPaperSize:];,pickedPaperSize:

- pickedPaperSize:sender

Performed when the user selects a paper size from the Paper Size list.  This method updates the Width and Height fields, redraws the paper view, and may switch the Portrait/Landscape orientation.  The following demonstrates how to retrieve the name of a paper size and an NXSize describing the paper's dimensions from the paperSizeList instance variable:

const char *paperName = [[paperSizeList selectedCell] title];
const NXSize *paperSize = NXFindPaperSize(paperName);

Returns self.

NS_DEV_DOCFOR:objc_method:[PageLayout-pickedUnits:];,pickedUnits:

- pickedUnits:sender

Performed when the user selects a new unit of measurement from the Units list.  The height and width fields are updated.  Controls in the accessory view that express dimensions on the page must be converted to the new unit of measurement.  The ratios returned by convertOldFactor:newFactor: method should be used to calculate the new values, as shown below.  In the example, a hypothetical PageLayout subclass uses a TextField (myField) to display a value measured in the chosen units:

- pickedUnits:sender
{
    float old, new;

    /* At this point the units have been selected */
    /* but not set. Get the conversion factors. */
    [self convertOldFactor:&old newFactor:&new];

    /* Set myField based on the conversion factors. */
    [myField setFloatValue:([myField floatValue] * new / old)];

    /* Set the selected units. */
    return [super pickedUnits:sender];
}

Returns self.

See also:  - convertOldFactor:newFactor:

NS_DEV_DOCFOR:objc_method:[PageLayout-readPrintInfo];,readPrintInfo

- readPrintInfo

Reads the Application's global PrintInfo object, and sets the values of the Page Layout panel to those in the PrintInfo.  This method is invoked from the runModal method; you shouldn't need to invoke it yourself.  Returns self.

See also:  - writePrintInfo, - runModal

NS_DEV_DOCFOR:objc_method:[PageLayout-runModal];,runModal

- (int)runModal

Reads the pertinent data from the PrintInfo object into the PageLayout object and then runs the Page Layout panel in a modal loop.  When the user clicks the Cancel or OK button the loop is broken (from within the pickedButton: method), the panel is hidden, and, if the button was OK, the new PageLayout values are written to the PrintInfo object.  The method returns the tag of the button that the user clicked to dismiss the panel (either NX_OKTAG or NX_CANCELTAG).

This method is invoked by Application's runPageLayout method; an application is best served by running the Page Layout panel from that method rather than invoking this one directly. 

See also:  - runPageLayout (Application), - pickedButton:, - stopModal (Application), - runModalFor: (Application)

NS_DEV_DOCFOR:objc_method:[PageLayout-setAccessoryView:];,setAccessoryView:

- setAccessoryView:aView

Adds aView to the PageLayout's view hierarchy.  Applications can invoke this method to add a View that contains their own controls.  The panel is automatically resized to accommodate aView.  This method can be invoked repeatedly to change the accessory view depending on the situation.  If aView is nil, the panel's current accessory view, if any, is removed.  Returns the old accessory view.

See also:  - accessoryView

NS_DEV_DOCFOR:objc_method:[PageLayout-textDidEnd:endChar:];,textDidEnd:endChar:

- textDidEnd:textObject endChar:(unsigned short)theChar

Performed when the user finishes typing in the Height or Width forms.  The Paper Size list and Orientation matrix may change.  You can override this method to update other controls you add to the panel.  Returns self.

NS_DEV_DOCFOR:objc_method:[PageLayout-textWillChange:];,textWillChange:

- (BOOL)textWillChange:textObject

You never invoke this method directly; it's invoked when the user types in a page size.  This method highlights the ªOtherº choice in the list of paper types.  You can override this method to update other controls you add to the panel.  

See also:  - setAccessoryView:, - textWillChange: (Text delegate)

NS_DEV_DOCFOR:objc_method:[PageLayout-writePrintInfo];,writePrintInfo

- writePrintInfo

Writes the settings of the Page Layout panel to the Application object's global PrintInfo object.  This method is invoked when the user quits the Page Layout panel by clicking the OK button.  Returns self.

See also:  - readPrintInfo, - runModal